sequenceDiagram
  actor Developer
  participant CursorClient
  participant McpServer
  participant NodeFs as Fs

  Developer->>CursorClient: Request tool quantlab_artifact_read(relative_path)
  CursorClient->>McpServer: callTool quantlab_artifact_read(relative_path)

  McpServer->>McpServer: resolveOutputsPath(relative_path)
  McpServer->>Fs: stat(resolvedPath)
  Fs-->>McpServer: FileStat
  alt path_is_directory
    McpServer-->>CursorClient: isError=true, message "Expected a file under outputs/"
  else binary_extension
    McpServer-->>CursorClient: isError=true, message "Binary artifact reading is not supported"
  else text_file
    McpServer->>Fs: readFile(resolvedPath, "utf8")
    Fs-->>McpServer: content
    McpServer->>McpServer: build payload (bytes, modified_at, truncated, content)
    McpServer-->>CursorClient: content text with metadata and artifact body
  end

  CursorClient-->>Developer: Display tool result

flowchart TD
  start([Start])

  subgraph list_tool[quantlab_outputs_list]
    L1{{"Tool called with optional relative_path"}}
    L1 --> L2["Resolve path under outputs/ using resolveOutputsPath"]
    L2 --> L3["fs.stat(targetPath)"]
    L3 --> L4{Is directory?}
    L4 -- No --> Lerr["Error: not a directory under outputs/"]
    L4 -- Yes --> L5["fs.readdir(targetPath, withFileTypes=true)"]
    L5 --> L6["For each entry: fs.stat(entryPath)"]
    L6 --> L7["Build metadata: name, kind, relative_path, size_bytes, size_human, modified_at"]
    L7 --> L8["Sort: directories first, then files by name"]
    L8 --> L9["Return JSON payload (root, requested_path, absolute_path, entry_count, entries)"]
  end

  subgraph read_tool[quantlab_artifact_read]
    R1{{"Tool called with relative_path"}}
    R1 --> R2["Resolve path under outputs/ using resolveOutputsPath"]
    R2 --> R3["fs.stat(targetPath)"]
    R3 --> R4{Is directory?}
    R4 -- Yes --> Rerr1["Error: expected a file under outputs/"]
    R4 -- No --> R5{Binary extension?}
    R5 -- Yes --> Rerr2["Error: binary artifact reading not supported"]
    R5 -- No --> R6["fs.readFile(targetPath, utf8)"]
    R6 --> R7["Apply truncateText to enforce MAX_OUTPUT_CHARS"]
    R7 --> R8["Build response: bytes, modified_at, truncated flag, content"]
    R8 --> R9["Return formatted text block with metadata and content"]
  end

  start --> L1
  start --> R1